Pasteboard#

The Pasteboard namespace provides a complete interface for reading, writing, and observing system pasteboard (clipboard) changes in the Scripting app. Compared to the deprecated Clipboard API, Pasteboard offers more robust features, including:

• Support for multiple data types (text, images, URLs, binary data, etc.)
• Change event callbacks (onChanged and onRemoved)
• Privacy controls such as localOnly and expiration time

Note To allow pasting from other apps, go to: Settings > Scripting > Paste from Other Apps > Allow

Namespace: Pasteboard#

Type Definition#

Item#

Represents a pasteboard item. Each item is a map (Record<UTType, string | UIImage | Data>) where the key is a data type (UTType) and the value can be a string, image, or binary data.

Common types:

• public.plain-text → plain text
• public.url → URL string
• public.jpeg / public.png → image (UIImage)
• public.data → binary data (Data)

Example

1const item: Pasteboard.Item = {
2  "public.plain-text": "Hello, world!",
3  "public.url": "https://example.com"
4}

Properties#

hasStrings: Promise<boolean>#

Checks whether the pasteboard contains text content.

Example

1if (await Pasteboard.hasStrings) {
2  console.log("Pasteboard contains text")
3}

hasImages: Promise<boolean>#

Checks whether the pasteboard contains images.

Example

1if (await Pasteboard.hasImages) {
2  console.log("Pasteboard contains images")
3}

hasURLs: Promise<boolean>#

Checks whether the pasteboard contains URLs.

Example

1if (await Pasteboard.hasURLs) {
2  console.log("Pasteboard contains URLs")
3}

numberOfItems: Promise<number>#

Returns the number of items currently stored in the pasteboard.

Example

1const count = await Pasteboard.numberOfItems
2console.log(`The pasteboard contains ${count} items`)

changeCount: Promise<number>#

Returns the number of times the pasteboard contents have changed since system startup. This value increases whenever the pasteboard is modified (items added, updated, or removed).

Example

1const changeCount = await Pasteboard.changeCount
2console.log("Pasteboard change count:", changeCount)

Text Operations#

getString(): Promise<string | null>#

Retrieves the text string of the first pasteboard item.

Example

1const text = await Pasteboard.getString()
2if (text) console.log("Pasteboard text:", text)

setString(string: string | null): Promise<void>#

Sets the text string of the first pasteboard item.

Example

1await Pasteboard.setString("Scripting is powerful!")

getStrings(): Promise<string[] | null>#

Retrieves all text strings from the pasteboard.

Example

1const texts = await Pasteboard.getStrings()
2console.log(texts)

setStrings(strings: string[] | null): Promise<void>#

Sets multiple text strings to the pasteboard (each string becomes a separate item).

Example

1await Pasteboard.setStrings(["Apple", "Banana", "Cherry"])

URL Operations#

getURL(): Promise<string | null>#

Retrieves the first URL string from the pasteboard.

Example

1const url = await Pasteboard.getURL()
2if (url) console.log("Pasteboard URL:", url)

setURL(url: string | null): Promise<void>#

Sets a URL string as the first pasteboard item.

Example

1await Pasteboard.setURL("https://example.com")

getURLs(): Promise<string[] | null>#

Retrieves all URL strings from the pasteboard.

Example

1const urls = await Pasteboard.getURLs()
2console.log(urls)

setURLs(urls: string[] | null): Promise<void>#

Sets multiple URLs to the pasteboard.

Example

1await Pasteboard.setURLs([
2  "https://apple.com",
3  "https://openai.com"
4])

Image Operations#

getImage(): Promise<UIImage | null>#

Retrieves the first image (UIImage) from the pasteboard.

Example

1const img = await Pasteboard.getImage()
2if (img) console.log("Image retrieved from pasteboard")

setImage(image: UIImage | null): Promise<void>#

Sets the first pasteboard item to an image.

Example

1await Pasteboard.setImage(myImage)

getImages(): Promise<UIImage[] | null>#

Retrieves all image objects from the pasteboard.

Example

1const images = await Pasteboard.getImages()
2console.log(`Retrieved ${images?.length ?? 0} images`)

setImages(images: UIImage[] | null): Promise<void>#

Sets multiple images to the pasteboard.

Example

1await Pasteboard.setImages([img1, img2, img3])

Item Management#

addItems(items: Item[]): Promise<void>#

Appends new items to the existing pasteboard content without clearing it.

Example

1await Pasteboard.addItems([
2  { "public.plain-text": "First item" },
3  { "public.url": "https://example.com" }
4])

setItems(items: Item[], options?: { localOnly?: boolean, expirationDate?: Date }): Promise<void>#

Replaces the pasteboard contents with new items and applies optional privacy settings.

Parameters

• items: An array of pasteboard items.
• options.localOnly: If true, prevents the pasteboard content from being shared to other devices via Handoff.
• options.expirationDate: Sets an expiration time after which the system automatically removes the content.

Example

1await Pasteboard.setItems(
2  [
3    { "public.plain-text": "Sensitive Info" }
4  ],
5  {
6    localOnly: true,
7    expirationDate: new Date(Date.now() + 60 * 1000) // Expires in 1 minute
8  }
9)

getItems(): Promise<Item[] | null>#

Retrieves all pasteboard items as an array of Pasteboard.Item objects.

Example

1const items = await Pasteboard.getItems()
2console.log(items)

Event Callbacks#

onChanged: ((addedKeys: string[]) => void) | null | undefined#

Called when the pasteboard content changes. The parameter addedKeys is an array of the added representation types (UTType).

Example

1Pasteboard.onChanged = addedKeys => {
2  console.log("Added pasteboard types:", addedKeys)
3}

onRemoved: ((removedKeys: string[]) => void) | null | undefined#

Called when content is removed from the pasteboard. The parameter removedKeys is an array of the removed representation types (UTType).

Example

1Pasteboard.onRemoved = removedKeys => {
2  console.log("Removed pasteboard types:", removedKeys)
3}

Deprecated Clipboard API#

The legacy Clipboard namespace is deprecated and retained only for backward compatibility.

Best Practices#

• Always use the new Pasteboard API instead of Clipboard.
• Use changeCount to detect when pasteboard contents have changed.
• Use expirationDate to automatically clear sensitive data after a specific duration.
• Set localOnly: true for data that should not sync across devices.
• Use hasStrings, hasImages, and hasURLs to check available content types before reading.
• Use onChanged and onRemoved callbacks to react in real time to pasteboard updates.